home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 2000 August: Tool Chest / Dev.CD Aug 00 TC Disk 2.toast / pc / sample code / interapplication comm / moreappleevents / osahelpers.h < prev    next >
Encoding:
C/C++ Source or Header  |  2000-06-23  |  9.3 KB  |  294 lines
  1. /*
  2.     File:        OSAHelpers.h
  3.  
  4.     Contains:    Functions to help you when you are working with the OSA.
  5.  
  6.     Written by: Andy Bachorski    
  7.  
  8.     Copyright:    Copyright © 1996-1999 by Apple Computer, Inc., All Rights Reserved.
  9.  
  10.                 You may incorporate this Apple sample source code into your program(s) without
  11.                 restriction. This Apple sample source code has been provided "AS IS" and the
  12.                 responsibility for its operation is yours. You are not permitted to redistribute
  13.                 this Apple sample source code as "Apple sample source code" after having made
  14.                 changes. If you're going to re-distribute the source, we require that you make
  15.                 it clear in the source that the code was descended from Apple sample source
  16.                 code, but that you've made changes.
  17.  
  18.     Change History (most recent first):
  19.                 7/21/1999    Karl Groethe    Updated for Metrowerks Codewarror Pro 2.1
  20.                 
  21.  
  22. */
  23.  
  24. #if PRAGMA_ONCE
  25.     #pragma once
  26. #endif
  27.  
  28. #ifndef _OSA_HELPERS_
  29. #define _OSA_HELPERS_
  30.  
  31.  
  32. //******************************************************************************
  33. //    A private conditionals file to setup the build environment for this project.
  34.  
  35. #include "PrivateConditionals.h"
  36.  
  37.  
  38. //**********    Universal Headers        ****************************************
  39.  
  40. #include <AppleScript.h>
  41. #include <Components.h>
  42. #include <Files.h>
  43. #include <OSA.h>
  44.  
  45.  
  46. #ifdef __cplusplus
  47.     extern "C" {
  48. #endif
  49.  
  50. #if PRAGMA_IMPORT
  51.     #pragma import on
  52. #endif
  53.  
  54. #if PRAGMA_STRUCT_ALIGN
  55.     #pragma options align=mac68k
  56. #elif PRAGMA_STRUCT_PACKPUSH
  57.     #pragma pack(push, 2)
  58. #elif PRAGMA_STRUCT_PACK
  59.     #pragma pack(2)
  60. #endif
  61.  
  62. //******************************************************************************
  63.  
  64. #define EVENPAD(ptr) ( ( (ptr) + 1 ) & 0xfffffffe )
  65.  
  66.  
  67. enum {
  68.     kScriptResID        = 128
  69. };
  70.  
  71.  
  72.  
  73. #define kHandlerNameHeaderSize        8    // The size of everything before name below
  74.  
  75. struct HandlerNameList {
  76.     DescType        nameType;
  77.     long            nameLength;
  78.     char            name[1];    //    variable length, not terminated
  79. };
  80. typedef struct HandlerNameList HandlerNameList;
  81. typedef HandlerNameList *HandlerNameListPtr;
  82.  
  83.  
  84. //******************************************************************************
  85.  
  86. pascal Boolean OSAHAppleScriptIsPresent( void );
  87. /*
  88.     Checks for the presence of the AppleScript OSA component.
  89.     
  90.     RESULT CODES
  91.     ____________
  92.     true        AppleScript is present and available
  93.     false        It isn't
  94.     ____________
  95. */
  96.  
  97. //******************************************************************************
  98.  
  99. pascal OSErr OSAHOpenGenericScriptingComponent( ComponentInstance *compInstPtr );
  100. /*
  101.     Open the default scripting component.
  102.  
  103.     componentInstance    input:    Pointer to ComponentInstance variable.
  104.                         output:    The newly opened scripting component, or nil if error.
  105.     
  106.     RESULT CODES
  107.     ____________
  108.     noErr                         0    No error    
  109.     errOSACantOpenComponent    -1762    Can't connect to scripting system with that ID
  110.     ____________
  111. */
  112.  
  113. //******************************************************************************
  114.  
  115. pascal OSErr OSAHOpenAppleScriptComponent( ComponentInstance *compInstPtr );
  116. /*
  117.     Open the ApppleScript scripting component.
  118.  
  119.     componentInstance    input:    Pointer to ComponentInstance variable.
  120.                         output:    The newly opened scripting component, or nil if error.
  121.     
  122.     RESULT CODES
  123.     ____________
  124.     noErr                         0    No error    
  125.     errOSACantOpenComponent    -1762    Can't connect to scripting system with that ID
  126.     ____________
  127. */
  128.  
  129. //******************************************************************************
  130.  
  131. pascal OSErr OSAHLoadScriptResource( ComponentInstance componentInstance,
  132.                               short resFileRef,
  133.                               short scriptResID,
  134.                               OSAID *scriptIDPtr );
  135. /*
  136.     Load a script resource for the given component instance.
  137.     
  138.     componentInstance    input:    Component instance to load script into.
  139.     resFileRef            input:    Resource file to get script from.
  140.     scriptResID            input:    Script (type 'scpt') resource ID to load.
  141.     scriptIDPtr            input:    Pointer to OSAID to return the loaded script ID in.
  142.                         output:    The newly loaded script ID.
  143.     
  144.     RESULT CODES
  145.     ____________
  146.     noErr                             0    No error    
  147.     resNotFound                     -192    Can't find the requested resource
  148.     errOSACorruptData            -1702    Corrupt data    
  149.     errOSASystemError            -1750    General scripting system error    
  150.     errOSABadStorageType        -1752    Script data not for this scripting component
  151.     errOSADataFormatObsolete    -1758    Data format is obsolete    
  152.     errOSADataFormatTooNew        -1759    Data format is too new    
  153.     badComponentInstance    $80008001    Invalid component instance    
  154.     ____________
  155. */
  156.  
  157. //******************************************************************************
  158.  
  159. pascal OSErr OSAHUnloadScriptResource( ComponentInstance componentInstance,
  160.                                 short resFileRef,
  161.                                 short scriptResID,
  162.                                 OSAID scriptID );
  163. /*
  164.     Dispose of a script for the given component instance.  If there have been
  165.     changes to the script, it is saved before being unloaded.
  166.     
  167.  
  168.     componentInstance    input:    Component instance to load script into.
  169.     resFileRef            input:    Resource file to get script from.
  170.     scriptResID            input:    Script (type 'scpt') resource ID to load.
  171.     scriptIDPtr            input:    OSAID to return the loaded script ID in.
  172.     
  173.     RESULT CODES
  174.     ____________
  175.     noErr                             0    No error    
  176.     memFullErr                     -108    Not enough memory    
  177.     nilHandleErr                 -109    NIL master pointer    
  178.     memWZErr                     -111    Attempt to operate on a free block    
  179.     resNotFound                     -192    Can't find the requested resource
  180.     resAttrErr                     –198    Attribute inconsistent with operation
  181.     errOSASystemError            -1750    General scripting system error    
  182.     errOSAInvalidID                -1751    Invalid script ID    
  183.     errOSABadStorageType        -1752    Desired type not supported by this scripting component       
  184.     errOSABadSelector            -1754    Selector value not supported by scripting component    
  185.     badComponentInstance    $80008001    Invalid component instance    
  186.     ____________
  187. */
  188.  
  189. // *****************************************************************************
  190.  
  191. pascal OSAError OSAHGetHandlerNames( ComponentInstance compInst, OSAID scriptID, AEDescList* handlerListPtr );
  192. /*
  193.     Given an AppleScript script ID, return an list containing the names of all
  194.     handlers inplemented in the script.
  195.     
  196.     NOTE:  Valid only for AppleScript scripts.
  197.     
  198.     Esentially a wrapper around OSAGetHandlerNames() that allows you to pass in either
  199.     a generic or AppleScript component instance.
  200.     
  201.     Returns a list of handler names (typeChar)
  202.     
  203.     The handler name for subroutines, sometimes called named handlers, for should be of 
  204.     typeChar and be in cononical form, i.e., all lower case with diacriticals removed.  
  205.     The name of a handler for a standard event (run, open, or «event xxxxyyyy») will be 
  206.     8 characters long, and will be of the form clasIDID where 'clas' is the event class 
  207.     and 'IDID' is the eventID.
  208.  
  209.     
  210.     compInst        input:    A generic or AppleScript component instance.
  211.     scriptID        input:    The script to get the handler names from.
  212.     nameDescPtr        input:    A list to contain the handler names.
  213.     
  214.     RESULT CODES
  215.     ____________
  216.     ____________
  217. */
  218.  
  219. // *****************************************************************************
  220.  
  221. pascal Boolean OSAHHandlerIsInHandlerList( const AEDescList *handlerListPtr, const AEDesc *nameDescPtr );
  222. /*
  223.     Look for a particular handler name in a list of handler names (as returned by OSAHGetHandlerNames()).
  224.     
  225.     The handler name for subroutines, sometimes called named handlers, for should be of 
  226.     typeChar and be in cononical form, i.e., all lower case with diacriticals removed.  
  227.     The name of a handler for a standard event (run, open, or «event xxxxyyyy») will be 
  228.     8 characters long, and will be of the form clasIDID where 'clas' is the event class 
  229.     and 'IDID' is the eventID.
  230.  
  231.     NOTE:  Valid only for AppleScript scripts.
  232.     
  233.     handlerListPtr        input:    The list of handler names for an AppleScript script.
  234.     resFileRef            input:    The handler name to check for, in cononical form.
  235.     nameDescPtr            input:    An string containing the name of the handler to look for
  236.     
  237.     RESULT CODES
  238.     ____________
  239.     ____________
  240. */
  241.  
  242. // *****************************************************************************
  243.  
  244. pascal Boolean OSAHScriptHasHandler( ComponentInstance compInst, OSAID scriptID, const AEDesc *nameDescPtr );
  245. /*
  246.     Check a script to see if it contains a particular handler.
  247.     
  248.     The handler name for subroutines, sometimes called named handlers, for should be of 
  249.     typeChar and be in cononical form, i.e., all lower case with diacriticals removed.  
  250.     The name of a handler for a standard event (run, open, or «event xxxxyyyy») will be 
  251.     8 characters long, and will be of the form clasIDID where 'clas' is the event class 
  252.     and 'IDID' is the eventID
  253.  
  254.     For subroutines, the input should be of type 'text' with the dataHandle
  255.     containing a lowercased name for AppleScript english scripts
  256.     For other event handlers (open, quite, «event clasIDID») the input should
  257.     be of type 'evnt' with the data handle containing the event class and ID
  258.     DescTypes, i.e., 8 bytes of the form [clasIDID]
  259.     
  260.     componentInstance    input:    Component instance for script.
  261.     resFileRef            input:    Script to get names from.
  262.     nameDescPtr            input:    A typeChar desc containing the name of the handler to look for
  263.                                 Note: Must be in cononical form, i.e., 'MyHandler' would be 'myhandler'.
  264.     
  265.     Returns a boolean indicating if the handler was found.
  266.     
  267.     RESULT CODES
  268.     ____________
  269.     ____________
  270. */
  271.  
  272. //******************************************************************************
  273.  
  274.  
  275. #if PRAGMA_STRUCT_ALIGN
  276.     #pragma options align=reset
  277. #elif PRAGMA_STRUCT_PACKPUSH
  278.     #pragma pack(pop)
  279. #elif PRAGMA_STRUCT_PACK
  280.     #pragma pack()
  281. #endif
  282.  
  283. #ifdef PRAGMA_IMPORT_OFF
  284. #pragma import off
  285. #elif PRAGMA_IMPORT
  286. #pragma import reset
  287. #endif
  288.  
  289. #ifdef __cplusplus
  290. }
  291. #endif
  292.  
  293. #endif // _OSA_HELPERS_
  294.